Size Change: +107 B (0%)

Total Size: 1.08 MB

_{compressed-size-action}

@ellatrix I think we should also update the documentation of the Component itself here: https://github.com/WordPress/gutenberg/blob/trunk/packages/block-editor/src/components/inner-blocks/README.md as part of this PR.

I can take care of that once you rebased this pr if that works for you (y)

Thank you @ellatrix for all your work on this :) I really appreciate your work here and just want you to know that it is very much appreciated! Excited for this to be I. 5.9 :)

Dev Note Draft:

Take more control over Inner Block Areas (as a block developer)

Prior to WordPress 5.9 the only way to work with inner block was to use the <InnerBlocks /> component. One downside of this approach is that in the editor this creates additional DOM nodes that wrap the markup of the inner blocks. This makes it more difficult to style these inner blocks areas to match what the enduser will see on the site.

With WordPress 5.9 we're introducing a new react hook called useInnerBlocksProps that allows you to change this and take more control over the markup of inner blocks areas. The useInnerBlocksProps is exported from the @wordpress/block-editor package same as the InnerBlocks component itself and supports everything the component does. It also works like the useBlockProps hook introduced with apiVersion: 2 in WordPress 5.6.

To use the hook, take the object returned from calling the hook and spread it onto the host element you want to render the inner blocks into. For example:

function BlockEdit(props) {
    const blockProps = useBlockProps();
    const innerBlocksProps = useInnerBlocksProps();

    return (
        <section {...blockProps}>
             <div {...innerBlocksProps} />
        </section>
    );
}

The above code will render to the following markup in the editor:

<section>
    <div>
        <!-- Inner Blocks get inserted here -->
    </div>
</section>

The hook also accepts two arguments:

1. The first argument accepts an object containing additional props that are added to the element in the dom. For example, to add a custom class name to the inner blocks area you pass { className: 'my-class' } as the first argument.
2. The second argument is also an object and can contain any properties to control the behavior of the inner blocks area. It accepts all options like allowedBlocks, template, templateLock, renderAppender, etc. You can find the full list of supported properties in the InnerBlocks props documentation

useInnerBlocksProps( additionalWrapperProps, innerBlocksProps );

Saving the inner blocks

To save inner blocks content there is a special variant of the hook, this is similar to the component-based approach that uses <InnerBlocks.Content /> in the save method of a block. For hooks, you add .save to the end of the hook like so:

function BlockSave( props ) {
    const innerBlocksProps = useInnerBlocksProps.save( { className: 'my-class' } );

    return (
        <section {...innerBlocksProps} ) />
    );
}

When you use the useInnerBlocksProps.save() hook it only accepts the first parameter, these are the options you want to add to the container element.

Why use hooks?

The hooks allow for new options and nice enhancements. For example, you can take the object returned from the useBlockProps hook—these contain the properties for the block's wrapping container—and pass them to the useInnerBlocksProps hook. This reduces the number of elements we need to create. For example:

function BlockEdit(props) {
    const blockProps = useBlockProps();
    const innerBlocksProps = useInnerBlocksProps( blockProps );

    return (
        <section {...innerBlocksProps} />
    );
}

<section>
    <!-- Inner Blocks get inserted here -->
</section>

Another benefit to using the hook approach is using the returned value, which is just an object, and deconstruct to get the react children from the object. This property contains the actual child inner blocks thus we can place elements on the same level as our inner blocks.

function BlockEdit(props) {
    const blockProps = useBlockProps();
    const { children, ...innerBlocksProps } = useInnerBlocksProps( blockProps );

    return (
        <section {...innerBlocksProps}>
            { children }
            <!-- Insert any arbitrary html here at the same level as the children -->
        </section>
    );
}

<section>
    <!-- Inner Blocks get inserted here -→
    <!-- The custom html gets rendered on the same level -->
</section>

Example:

block.json

{
    "apiVersion": 2,
    "name": "example/block",
    "title": "Example",
    "category": "text",
    "editorScript": "file:./index.js"
}

index.js

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';

import metadata from './block.json';

function BlockEdit(props) {
    const blockProps = useBlockProps( { className: 'my-class' } );
    const innerBlocksProps = useInnerBlocksProps(
        blockProps,
        { allowedBlocks: [ 'core/heading', 'core/paragraph', 'core/image' ] }
    );

    return (
        <section {...innerBlocksProps} />
    );
}

function BlockSave(props) {
    const blockProps = useBlockProps.save( { className: 'my-class' } );
    const innerBlocksProps = useInnerBlocksProps.save( blockProps );

    return <section {...innerBlocksProps} />
}

registerBlockType( metadata, {
    edit: BlockEdit,
    save: BlockSave,
} )

Tagging @gziolo @mkaz and @ellatrix for review

@fabiankaegy, great working putting this dev note together. It is nicely structured as each section builds on top of each other and includes nicely crafted examples. I don't know the new API fully but I find this explanation very informative 💯

One thing that would be worth explaining explicitly is that similar to how InnerBlocks and InnerBlocks.Content work, we have two different hooks for edit and save. I see that the last example covers it, but I almost missed that part.

@gziolo Updated the comment with a new section called Saving the inner blocks

@fabiankaegy This looks good, thanks for taking the time to put it together. I edited the note above for clarity and wording in a couple spots (you can see a diff of the edits using the dropdown).

It is good to publish to make/core, use the dev-notes and 5-9 tags. 🚀
Let me know if you have any questions. Thanks again! 🥇

https://make.wordpress.org/core/2021/12/28/take-more-control-over-inner-block-areas-as-a-block-developer/

Thank you for the dev note @fabiankaegy! It looks great.